News & Insights

**Referenced Files in This Document** - [news.njk](file://src/news.njk) - [news-article-card.njk](file://src/_includes/macros/news-article-card.njk) - [news.11tydata.json](file://src/content/news/news.11tydata.json) - [2025-10-17-political-powerhouse.md](file://src/content/news/2025-10-17-political-powerhouse.md) - [2025-11-03-political-stalwart.md](file://src/content/news/2025-11-03-political-stalwart.md) - [pages.json](file://src/_data/pages.json) - [.eleventy.js](file://.eleventy.js) - [base.njk](file://src/_includes/layouts/base.njk) - [config.yml](file://src/admin/config.yml) - [22-news-insights-page.css](file://src/assets/css/modules/22-news-insights-page.css) - [site.json](file://src/_data/site.json)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document explains the News & Insights content collection, covering frontmatter fields, rich text editing, media integration, and the end-to-end content workflow from drafting to publication. It also details how news items are presented via automatic news cards and filtering, how they relate to the main navigation, and how to optimize content for SEO and social sharing. Practical examples demonstrate metadata, image optimization, and category tagging.

Project Structure

The News & Insights system spans content files, Eleventy collections, Nunjucks templates, macros, and configuration for the CMS editor.

graph TB
subgraph "Content"
A["src/content/news/*.md"]
B["src/content/news/news.11tydata.json"]
end
subgraph "Eleventy"
C[".eleventy.js<br/>news collection + filters"]
end
subgraph "Templates"
D["src/news.njk<br/>News & Insights page"]
E["src/_includes/macros/news-article-card.njk<br/>News card macro"]
end
subgraph "Data"
F["src/_data/pages.json<br/>Hero + section labels"]
G["src/_data/site.json<br/>Site metadata"]
end
subgraph "UI/CMS"
H["src/assets/css/modules/22-news-insights-page.css<br/>Grid + filters"]
I["src/admin/config.yml<br/>CMS fields for News"]
end
A --> C
B --> C
C --> D
D --> E
F --> D
G --> D
D --> H
I --> D

Diagram sources

  • [news.njk:1-199](file://src/news.njk#L1-L199)
  • [news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2)
  • [.eleventy.js:170-174](file://.eleventy.js#L170-L174)
  • [pages.json:21-56](file://src/_data/pages.json#L21-L56)
  • [site.json:1-20](file://src/_data/site.json#L1-L20)
  • [22-news-insights-page.css:1-151](file://src/assets/css/modules/22-news-insights-page.css#L1-L151)
  • [config.yml:15-32](file://src/admin/config.yml#L15-L32)

Section sources

  • [news.njk:1-199](file://src/news.njk#L1-L199)
  • [news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [news.11tydata.json:1-2](file://src/content/news/news.11tydata.json#L1-L2)
  • [.eleventy.js:170-174](file://.eleventy.js#L170-L174)
  • [pages.json:21-56](file://src/_data/pages.json#L21-L56)
  • [site.json:1-20](file://src/_data/site.json#L1-L20)
  • [22-news-insights-page.css:1-151](file://src/assets/css/modules/22-news-insights-page.css#L1-L151)
  • [config.yml:15-32](file://src/admin/config.yml#L15-L32)

Core Components

  • Content entries: Markdown files under src/content/news with frontmatter and body.
  • Eleventy collection: A sorted “news” collection keyed by date.
  • Page template: src/news.njk renders the News & Insights page, including filtering and cards.
  • Macro: news-article-card.njk renders individual news cards in grid and carousel variants.
  • CMS configuration: src/admin/config.yml defines the News collection fields for the Netlify CMS editor.
  • Page data: src/_data/pages.json supplies labels and copy for the News page.
  • Site data: src/_data/site.json provides canonical URL and social metadata used in templates.
  • Styles: src/assets/css/modules/22-news-insights-page.css styles the grid, filters, and cards.

Section sources

  • [news.njk:91-127](file://src/news.njk#L91-L127)
  • [news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [config.yml:15-32](file://src/admin/config.yml#L15-L32)
  • [pages.json:21-56](file://src/_data/pages.json#L21-L56)
  • [site.json:1-20](file://src/_data/site.json#L1-L20)
  • [22-news-insights-page.css:97-151](file://src/assets/css/modules/22-news-insights-page.css#L97-L151)

Architecture Overview

The News & Insights pipeline:

sequenceDiagram
participant Author as "Author (Netlify CMS)"
participant CMS as "Netlify CMS (config.yml)"
participant FS as "Markdown Files (*.md)"
participant Eleventy as ".eleventy.js"
participant Page as "src/news.njk"
participant Macro as "news-article-card.njk"
participant Browser as "Browser"
Author->>CMS : Edit/create news entry
CMS->>FS : Save frontmatter + body
FS->>Eleventy : Files under src/content/news
Eleventy->>Eleventy : Build news collection (sorted by date)
Eleventy->>Page : Provide collections.news
Page->>Macro : Render cards for each news item
Browser->>Page : Load News & Insights page
Page->>Browser : Render grid + filters + cards

Diagram sources

  • [config.yml:15-32](file://src/admin/config.yml#L15-L32)
  • [.eleventy.js:170-174](file://.eleventy.js#L170-L174)
  • [news.njk:91-127](file://src/news.njk#L91-L127)
  • [news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)

Detailed Component Analysis

Frontmatter Fields and Rich Text Editing

  • Supported fields for News entries (Netlify CMS):
    • title, date, author, excerpt, image, image_alt, pdf_url, pdf_label, featured, draft, body (markdown).
  • Rich text editing:
    • The body uses markdown in the CMS, enabling headings, lists, emphasis, links, and blockquotes.
    • The rendered page displays the markdown body safely within the card’s expanded content area.

Practical example references:

  • Example frontmatter and body: [2025-10-17-political-powerhouse.md:1-18](file://src/content/news/2025-10-17-political-powerhouse.md#L1-L18)
  • Example frontmatter and body: [2025-11-03-political-stalwart.md:1-18](file://src/content/news/2025-11-03-political-stalwart.md#L1-L18)

Section sources

  • [config.yml:20-31](file://src/admin/config.yml#L20-L31)
  • [2025-10-17-political-powerhouse.md:1-18](file://src/content/news/2025-10-17-political-powerhouse.md#L1-L18)
  • [2025-11-03-political-stalwart.md:1-18](file://src/content/news/2025-11-03-political-stalwart.md#L1-L18)

Automatic News Cards and Grid Rendering

  • The News page iterates over the Eleventy news collection and renders each item via the news card macro.
  • The macro supports:
    • Grid variant with optional image, date, title, excerpt, and a “Read more” link.
    • Carousel variant for text-only cards.
  • Cards are styled with a responsive grid and hover effects.
flowchart TD
Start(["Render News Page"]) --> Iterate["Iterate collections.news"]
Iterate --> MacroCall["news-article-card.card(item, 'grid')"]
MacroCall --> Card["Render news-item with image/title/excerpt"]
Card --> Expandable{"Has expanded content?"}
Expandable --> |Yes| Details["Render details summary + content + optional PDF"]
Expandable --> |No| NextItem["Next item"]
Details --> NextItem
NextItem --> End(["Done"])

Diagram sources

  • [news.njk:108-112](file://src/news.njk#L108-L112)
  • [news-article-card.njk:9-32](file://src/_includes/macros/news-article-card.njk#L9-L32)

Section sources

  • [news.njk:91-127](file://src/news.njk#L91-L127)
  • [news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [22-news-insights-page.css:97-151](file://src/assets/css/modules/22-news-insights-page.css#L97-L151)

Filtering and Category Tagging

  • The page provides a filter bar to show “All”, “Media Releases”, “Announcements”, and “Insights”.
  • The macro sets a data-category attribute on each card using the item’s category (defaulting to announcement if absent).
  • Client-side JavaScript filters cards by matching the data-category against the selected filter button.
sequenceDiagram
participant User as "User"
participant UI as "Filter Buttons"
participant JS as "Client-side Script"
participant Cards as "News Cards"
User->>UI : Click filter button
UI->>JS : Dispatch click event
JS->>Cards : Compare data-category with filter
Cards-->>JS : Matched/Unmatched items
JS->>Cards : Show matched with animation, hide others

Diagram sources

  • [news.njk:101-106](file://src/news.njk#L101-L106)
  • [news.njk:166-195](file://src/news.njk#L166-L195)
  • [news-article-card.njk](file://src/_includes/macros/news-article-card.njk#L10)

Section sources

  • [news.njk:101-106](file://src/news.njk#L101-L106)
  • [news.njk:166-195](file://src/news.njk#L166-L195)
  • [news-article-card.njk](file://src/_includes/macros/news-article-card.njk#L10)

Content Creation Workflow: Drafting to Publication

  • Drafting:
    • Use Netlify CMS to create a new News entry; choose “Create new document” in the News collection.
    • Fill in title, date, author, excerpt, image, image_alt, optional PDF link/label, featured flag, draft toggle, and body.
  • Review and publish:
    • Keep draft checked until ready; commit/push to publish.
  • Presentation:
    • Published entries appear automatically on the News page, sorted by date.
    • Featured items can be highlighted elsewhere using the featured collection if configured.
flowchart TD
A["Open Netlify CMS"] --> B["Select News collection"]
B --> C["Create new document"]
C --> D["Fill frontmatter + body"]
D --> E{"Ready to publish?"}
E --> |No| F["Keep draft checked"]
E --> |Yes| G["Uncheck draft + save"]
G --> H["Commit/Publish"]
H --> I["Eleventy rebuilds news collection"]
I --> J["News page shows updated entry"]

Diagram sources

  • [config.yml:15-32](file://src/admin/config.yml#L15-L32)
  • [.eleventy.js:170-174](file://.eleventy.js#L170-L174)
  • [news.njk:91-127](file://src/news.njk#L91-L127)

Section sources

  • [config.yml:15-32](file://src/admin/config.yml#L15-L32)
  • [.eleventy.js:170-174](file://.eleventy.js#L170-L174)
  • [news.njk:91-127](file://src/news.njk#L91-L127)

SEO and Social Media Sharing

  • Canonical URL and Open Graph/Twitter metadata are injected in the base layout.
  • Structured data for NewsArticle is included on News pages and post-like pages.
  • Social image defaults are provided if none is set.
graph LR
A["base.njk head"] --> B["Meta description + canonical"]
A --> C["Open Graph + Twitter cards"]
A --> D["NewsArticle structured data"]
E["site.json"] --> B
E --> C

Diagram sources

  • [base.njk:6-21](file://src/_includes/layouts/base.njk#L6-L21)
  • [base.njk:45-61](file://src/_includes/layouts/base.njk#L45-L61)
  • [site.json:1-20](file://src/_data/site.json#L1-L20)

Section sources

  • [base.njk:6-21](file://src/_includes/layouts/base.njk#L6-L21)
  • [base.njk:45-61](file://src/_includes/layouts/base.njk#L45-L61)
  • [site.json:1-20](file://src/_data/site.json#L1-L20)

Relationship with Main Navigation and Cross-Page Visibility

  • The News link is present in the main navigation and highlights when on the News page.
  • News items appear on:
    • The News & Insights page (grid + filters).
    • The homepage carousel (via the news carousel module).
    • Any page that includes the news collection (e.g., via macros or partials).
graph TB
Nav["base.njk nav"] --> NewsLink["/news/"]
NewsLink --> NewsPage["src/news.njk"]
NewsPage --> Cards["news-article-card.njk"]
Cards --> Grid["22-news-insights-page.css grid"]

Diagram sources

  • [base.njk:70-85](file://src/_includes/layouts/base.njk#L70-L85)
  • [news.njk:1-199](file://src/news.njk#L1-L199)
  • [news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [22-news-insights-page.css:97-151](file://src/assets/css/modules/22-news-insights-page.css#L97-L151)

Section sources

  • [base.njk:70-85](file://src/_includes/layouts/base.njk#L70-L85)
  • [news.njk:1-199](file://src/news.njk#L1-L199)
  • [news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [22-news-insights-page.css:97-151](file://src/assets/css/modules/22-news-insights-page.css#L97-L151)

Practical Examples

  • Creating a news article with proper metadata:
    • Use frontmatter keys: title, date, author, excerpt, image, image_alt, pdf_url, pdf_label, featured.
    • Populate the body with markdown for rich text.
    • Example frontmatter/body: [2025-10-17-political-powerhouse.md:1-18](file://src/content/news/2025-10-17-political-powerhouse.md#L1-L18)
    • Example frontmatter/body: [2025-11-03-political-stalwart.md:1-18](file://src/content/news/2025-11-03-political-stalwart.md#L1-L18)
  • Image optimization:
    • Place images under the CMS media folder and reference them in the image field.
    • Ensure alt text is set in image_alt for accessibility and SEO.
  • Category tagging:
    • Use the category attribute on cards; the filter bar matches against data-category.
    • Default category is applied if omitted.

Section sources

  • [2025-10-17-political-powerhouse.md:1-18](file://src/content/news/2025-10-17-political-powerhouse.md#L1-L18)
  • [2025-11-03-political-stalwart.md:1-18](file://src/content/news/2025-11-03-political-stalwart.md#L1-L18)
  • [news-article-card.njk](file://src/_includes/macros/news-article-card.njk#L10)
  • [config.yml:20-31](file://src/admin/config.yml#L20-L31)

Content Organization, Trending Topics, Seasonal Planning

  • Organization:
    • Use the date frontmatter to keep chronological order; Eleventy sorts by date automatically.
    • Use the featured flag to highlight important items across the site.
  • Trending topics:
    • Monitor engagement and promote relevant articles; consider linking from the homepage carousel or dedicated sections.
  • Seasonal content:
    • Plan releases around elections, policy cycles, and industry events; schedule dates accordingly.

[No sources needed since this section provides general guidance]

Dependency Analysis

  • Collections:
    • The news collection is defined in Eleventy and sorted by date.
  • Templates:
    • The News page depends on the news collection and the news card macro.
  • Macros:
    • The card macro reads frontmatter fields and optionally expands content.
  • Styles:
    • The news grid and filter bar are styled via the dedicated CSS module.
  • CMS:
    • The Netlify CMS config enforces the frontmatter schema for News entries.
graph LR
MD["*.md (frontmatter + body)"] --> COL["Eleventy news collection"]
COL --> TPL["src/news.njk"]
TPL --> MAC["news-article-card.njk"]
MAC --> CSS["22-news-insights-page.css"]
CFG["admin/config.yml"] --> MD

Diagram sources

  • [.eleventy.js:170-174](file://.eleventy.js#L170-L174)
  • [news.njk:108-112](file://src/news.njk#L108-L112)
  • [news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [22-news-insights-page.css:97-151](file://src/assets/css/modules/22-news-insights-page.css#L97-L151)
  • [config.yml:15-32](file://src/admin/config.yml#L15-L32)

Section sources

  • [.eleventy.js:170-174](file://.eleventy.js#L170-L174)
  • [news.njk:91-127](file://src/news.njk#L91-L127)
  • [news-article-card.njk:1-35](file://src/_includes/macros/news-article-card.njk#L1-L35)
  • [22-news-insights-page.css:97-151](file://src/assets/css/modules/22-news-insights-page.css#L97-L151)
  • [config.yml:15-32](file://src/admin/config.yml#L15-L32)

Performance Considerations

  • Lazy-loading images: The card macro uses loading="lazy" for images.
  • Minimal client-side scripting: Filtering is handled with vanilla JS and GSAP animations.
  • CSS modules: Dedicated styles keep rendering efficient and scoped.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • News item not appearing:
    • Verify the file is under src/content/news and named with a valid date prefix.
    • Confirm the draft flag is unchecked and the file has valid frontmatter.
  • Sorting incorrect:
    • Ensure the date frontmatter is valid and follows a sortable format.
  • Filters not working:
    • Confirm the category attribute exists or defaults are acceptable.
    • Check that data-category attributes are present on cards.
  • SEO issues:
    • Ensure description and title are set; confirm canonical URL and social image are correct.

Section sources

  • [news.njk:101-106](file://src/news.njk#L101-L106)
  • [news.njk:166-195](file://src/news.njk#L166-L195)
  • [news-article-card.njk](file://src/_includes/macros/news-article-card.njk#L10)
  • [site.json:1-20](file://src/_data/site.json#L1-L20)

Conclusion

The News & Insights system integrates CMS-driven content creation, Eleventy-powered collections, and a flexible Nunjucks template with a reusable card macro. Authors can efficiently manage rich text, media, and metadata while editors benefit from intuitive filtering and presentation. SEO and social sharing are supported through standardized metadata and structured data.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Appendix A: Frontmatter Field Reference

  • title: Article headline.
  • date: Publication date (sortable).
  • author: Author attribution.
  • excerpt: Short description for listings.
  • image: Path to featured image.
  • image_alt: Alt text for accessibility.
  • pdf_url: Optional downloadable PDF link.
  • pdf_label: Optional label for the PDF link.
  • featured: Boolean to mark featured items.
  • draft: Boolean to keep content private during editing.
  • body: Markdown content for the article.

Section sources

  • [config.yml:20-31](file://src/admin/config.yml#L20-L31)
  • [2025-10-17-political-powerhouse.md:1-18](file://src/content/news/2025-10-17-political-powerhouse.md#L1-L18)
  • [2025-11-03-political-stalwart.md:1-18](file://src/content/news/2025-11-03-political-stalwart.md#L1-L18)